<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>nftw</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_883">&nbsp;</a>NAME</h4><blockquote>
nftw - walk a file tree
</blockquote><h4><a name = "tag_000_007_884">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="ftw.h.html">ftw.h</a>&gt;

int nftw(const char *<i>path</i>, int (*<i>fn</i>)(const char *,
    const struct stat *, int, struct FTW *), int <i>depth</i>, int <i>flags</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_885">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>nftw()</i>
function recursively descends the directory hierarchy rooted in
<i>path</i>.
The
<i>nftw()</i>
function has a similar effect to
<i><a href="ftw.html">ftw()</a></i>
except that it takes an additional argument <i>flags</i>, which is
a bitwise inclusive-OR of zero or more of the following flags:
<dl compact>

<dt>FTW_CHDIR<dd>
If set,
<i>nftw()</i>
will change the current working directory to each directory as it
reports files in that directory.  If clear,
<i>nftw()</i>
will not change the current working directory.

<dt>FTW_DEPTH<dd>
If set,
<i>nftw()</i>
will report all files in a directory before reporting the directory itself.
If clear,
<i>nftw()</i>
will report any directory before reporting the files in that directory.

<dt>FTW_MOUNT<dd>
If set,
<i>nftw()</i>
will only report files in the same file system as
<i>path</i>.
If clear,
<i>nftw()</i>
will report all files encountered during the walk.

<dt>FTW_PHYS<dd>
If set,
<i>nftw()</i>
performs a physical walk and does not follow symbolic links.  If clear,
<i>nftw()</i>
will follow links instead of reporting them,
and will not report the same file twice.

</dl>
<p>
At each file it encounters,
<i>nftw()</i>
calls the user-supplied function
<i>fn()</i>
with four arguments:
<ul>
<p>
<li>
The first argument is the pathname of the object.
<p>
<li>
The second argument is a pointer to the <b>stat</b> buffer containing
information on the object.
<p>
<li>
The third argument is an integer giving additional information.  Its value is
one of the following:
<dl compact>

<dt>FTW_F<dd>
The object is a file.

<dt>FTW_D<dd>
The object is a directory.

<dt>FTW_DP<dd>
The object is a directory and subdirectories have been visited.
(This condition will only occur if the FTW_DEPTH flag is
included in <i>flags</i>.)

<dt>FTW_SL<dd>
The object is a symbolic link.
(This condition will only occur if the FTW_PHYS flag is
included in <i>flags</i>.)

<dt>FTW_SLN<dd>
The object is a symbolic link that does not name an existing file.
(This condition will only occur if the FTW_PHYS flag is not
included in <i>flags</i>.)

<dt>FTW_DNR<dd>
The object is a directory that cannot be read.  The
<i>fn()</i>
function will not be called for any of its descendants.

<dt>FTW_NS<dd>
The
<i><a href="stat.html">stat()</a></i>
function failed on the object because of lack of appropriate permission.  The
<b>stat</b> buffer passed to
<i>fn()</i>
is undefined.  Failure of
<i><a href="stat.html">stat()</a></i>
for any other reason is considered an error and
<i>nftw()</i>
returns -1.

</dl>
<p>
<li>
The fourth argument is a pointer to an <b>FTW</b> structure.
The value of <b>base</b> is the offset of the object's filename in the
pathname passed as the first argument to
<i>fn()</i>.
The value of <b>level</b> indicates depth relative to the root of of the walk,
where the root level is 0.
<p>
</ul>
<p>
The argument <i>depth</i> sets the maximum number of file descriptors that
will be used by 
<i>nftw()</i>
while traversing the file tree. At most one file
descriptor will be used for each directory level.
</blockquote><h4><a name = "tag_000_007_886">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i>nftw()</i>
function continues until the first of the following conditions occurs:
<ul>
<p>
<li>
An invocation of
<i>fn()</i>
returns a non-zero value, in which case
<i>nftw()</i>
returns that value.
<p>
<li>
The
<i>nftw()</i>
function detects an error other than [EACCES] (see FTW_DNR and FTW_NS above),
in which case
<i>nftw()</i>
returns -1 and sets <i>errno</i> to indicate the error.
<p>
<li>
The tree is exhausted, in which case
<i>nftw()</i>
returns 0.
<p>
</ul>
</blockquote><h4><a name = "tag_000_007_887">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>nftw()</i>
function will fail if:
<dl compact>

<dt>[EACCES]<dd>
Search permission is denied for any component of <i>path</i>
or read permission is denied for <i>path</i>, or
<i>fn()</i>
returns -1 and does not reset <i>errno</i>.

<dt>[ENAMETOOLONG]<dd>

The length of the <i>path</i> string exceeds {PATH_MAX}, or a
pathname component is longer than {NAME_MAX}.

<dt>[ENOENT]<dd>
A component of <i>path</i> does not name an existing file
or <i>path</i> is an empty string.

<dt>[ENOTDIR]<dd>
A component of <i>path</i> is not a directory.

</dl>
<p>
The
<i>nftw()</i>
function may fail if:
<dl compact>

<dt>[ELOOP]<dd>
Too many symbolic links were encountered in resolving <i>path</i>.

<dt>[EMFILE]<dd>
{OPEN_MAX} file descriptors are currently open in the calling process.

<dt>[ENAMETOOLONG]<dd>

Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

<dt>[ENFILE]<dd>
Too many files are currently open in the system.

</dl>
<p>
In addition, <i>errno</i> may be set if the function pointed by
<i>fn()</i>
causes <i>errno</i> to be set.
</blockquote><h4><a name = "tag_000_007_888">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_889">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_890">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_891">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="lstat.html">lstat()</a></i>,
<i><a href="opendir.html">opendir()</a></i>,
<i><a href="readdir.html">readdir()</a></i>,
<i><a href="stat.html">stat()</a></i>,
<i><a href="ftw.h.html">&lt;ftw.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
